home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / hard / hack / i2clib40.lha / i2clib40 / Developer / ChangesV39 next >
Text File  |  1998-08-30  |  6KB  |  183 lines
  1.  
  2. Changes from V38 to V39
  3. =======================
  4.  
  5. Explanation:
  6. · "beauty changes" to the include-files
  7. - changes in implementation
  8. * what that means for currently existing "V38 style" programs
  9. # recommended use for new "V39 aware" programs
  10.  
  11.  
  12. AllocI2C(delaytype,name)(D0,A1)
  13. -------------------------------
  14.  
  15. - Is being called automatically every time a new client opens the library.
  16. - Allocates the hardware to the library itself, not to the client, so the
  17.   A1 parameter is ignored.
  18. - Delay by means of the "timer.device" is no longer implemented, because
  19.   the new method of timing (idle CIA reads, which are slow on all Amigas)
  20.   is both precise and efficient. So the D0 parameter is ignored, too.
  21. # Don't use this function. If you want to have more than one try to
  22.   allocate the hardware, rather close the library and open it again. To
  23.   find out whether the hardware was successfully allocated (or why not),
  24.   just look at the error codes returned by SendI2C/ReceiveI2C.
  25.  
  26. I HAD to ignore the delaytype argument. At first I thought it might be
  27. helpful to interpret the delay value set by old style programs.  But that
  28. isn't true, because delay type and value aren't set simultaneously, and
  29. that means, not necessarily by the same program.
  30.  
  31.  
  32. FreeI2C()
  33. ---------
  34.  
  35. - Is being called automatically every time a client closes the library, but
  36.   does nothing while other clients have the library still open.
  37. * Obviously FreeI2C() can *fail* now, if more than one client has the
  38.   library open. That's bad if a program thinks it has e.g. returned the
  39.   hardware to the printer and then tries to print something.
  40. # Don't use this function. If you want to be nice while you do not need
  41.   the I²C bus for some time, rather close the library and open it again
  42.   later. If the system really needs the allocated hardware back
  43.   immediately, call ShutDownI2C(), but read the notes on that function!
  44.  
  45. An implementation of FreeI2C() that returns the hardware unconditionally,
  46. the way ShutDownI2C() does now, wouldn't have been a good solution. It
  47. would make old style programs, which call FreeI2C() when they quit, look
  48. like rotten bastards.
  49. So the current implementation at least allows peaceful coexistence. And
  50. if you've got a veteran program that really relies on FreeI2C() never to
  51. fail, just make sure you have no other I²C applications running at the
  52. same time.
  53.  
  54.  
  55. InitI2C()
  56. ---------
  57.  
  58. - Is being called automatically every time a new client opens the library,
  59.   but NOT after an explicit call to AllocI2C().
  60. # Use this function only, if you've called AllocI2C() explicitly. But you're
  61.   not supposed to do that, anyway.
  62.  
  63.  
  64. SetI2CDelay(ticks)(D0)
  65. ----------------------
  66.  
  67. · Has been renamed from formerly SetDelay.
  68. - Now returns the old delay value, too, and doesn't change the current
  69.   value at all, if I2CDELAY_READONLY is specified.
  70. - The delay value will always be translated to a loop of read accesses to
  71.   a CIA register in every SCL pulse.  These are slow (somewhere about a
  72.   microsecond), because of the dreadfully low clock rate that the Amiga
  73.   supplies to its CIAs.
  74. * When using DELAY_LOOP, the new delay method may look like power brakes:
  75.   old delay values will be much too high.
  76. * When using DELAY_TIMER with the recommended value of 10, the bus will
  77.   be running too slow, too.
  78. # You need not look at the return value, it's only useful to "spy" at the
  79.   delay value set by other programs.
  80.  
  81.  
  82. SendI2C(addr,number,data)(D0,D1,A1)   and
  83. -----------------------------------
  84. ReceiveI2C(addr,number,data)(D0,D1,A1)
  85. --------------------------------------
  86.  
  87. · Type of <number> is now "UWORD" ("int" was ambiguous).
  88. - The return value has been expanded from UBYTE to ULONG to supply
  89.   additional error information.
  90. - Both functions are protected by a semaphore now. That's why more than one
  91.   client at a time may use the library now, without them knowing about each
  92.   other.  (Of course, if two or more programs perform write accesses to the
  93.   same I²C address, this will still lead to problems.)
  94. - The LSB in <addr> is automatically corrected to form a valid read/write
  95.   address (foolproof).
  96. * Caution: When recompiling v38 style programs using the new header files,
  97.   error checking will most likely fail:  When considered as a ULONG, the
  98.   return values are now always non-zero (i.e. "success").
  99. # Application programs don't have to examine the error code in detail. They
  100.   should look at its low-order byte, and if it's zero (i. e. "error"), they
  101.   can let I2CErrText() do the rest (see example at the end of this file).
  102. # Obviously you can now use the same symbolic constant to address a chip for
  103.   both read and write.
  104.  
  105.  
  106. GetI2COpponent()
  107. ----------------
  108.  
  109. No changes.
  110.  
  111.  
  112.  
  113. New Functions in V39
  114. ====================
  115.  
  116. See "i2c.doc".
  117.  
  118.  
  119.  
  120. Examples
  121. ========
  122.  
  123. A minimal I²C program in the old style:
  124.  
  125. #define PCF8574_R 0x41
  126. #define PCF8574_W 0x40
  127.  
  128. main()
  129.     {
  130.     char i2cdata[ 10 ];
  131.  
  132.     if( (I2C_Base=OpenLibrary( "i2c.library", 37 )) == NULL )
  133.         return 10;
  134.     AllocI2C( DELAY_TIMER, "Charlie" );
  135.     InitI2C();
  136.     SetDelay( 10 );
  137.     if( !SendI2C( PCF8574_W, 1, i2cdata ) )
  138.         printf( "I²C failure!\n" );
  139.     if( !ReceiveI2C( PCF8574_R, 1, i2cdata ) )
  140.         printf("I²C failure!\n");
  141.     FreeI2C();
  142.     CloseLibrary( I2C_Base );
  143.     }
  144.  
  145.  
  146.  
  147. And the same for V39:
  148.  
  149. #define PCF8574 0x40
  150.  
  151. main()
  152.     {
  153.     char i2cdata[10];
  154.     ULONG err;
  155.  
  156.     if( (I2C_Base=OpenLibrary( "i2c.library", 39 )) == NULL )
  157.         return 10;
  158.     err = SendI2C( PCF8574, 1, i2cdata );
  159.     if( (err & 0xff)==0 )
  160.         printf( "I²C failure: %s!\n", I2CErrText( err ) );
  161.     err = ReceiveI2C( PCF8574, 1, i2cdata );
  162.     if( (err & 0xff)==0 )
  163.         printf( "I²C failure: %s!\n", I2CErrText( err ) );
  164.     CloseLibrary( I2C_Base );
  165.     }
  166.  
  167.  
  168.  
  169. Summary
  170. =======
  171.  
  172. A lot of neat stuff is new:  Automatic initialization during OpenLibrary,
  173. less trouble with the proper bus timing, better error diagnosis and the
  174. foolproof R/W address bit.  And most important, better support for I²C buses
  175. with more than one chip attached:  Each chip may now be controlled by a
  176. program of its own, and the programs will multitask nicely without even
  177. realizing they are not alone on the bus.
  178.  
  179. Existing binaries will continue to work, but be careful when recompiling
  180. old sources with the new headers. See the notes on SetI2CDelay, SendI2C
  181. and ReceiveI2C.
  182.  
  183.